Python |
您所在的位置：网站首页 › python docstring 规范 › Python |
|
1. python dostring规范（PEP）
来源：https://www.python.org/dev/peps/pep-0257/ 有好人翻译了重点的一部分，感谢：PEP 257 文档字符串规范总结 1.1 docstring的作用docstring是一种出现在模块、函数、类或者方法定义的第一行说明的字符串，这种docstring就会作为该对象的__docs__属性。 从规范角度来说，所有的模块都应该有docstrings，那些从模块中引入的函数和类也要有docstrings。公有方法（包括__init__构造器）也要有docstring。对于一个包来说，包的说明文档可能就来自__init__文件中的docstring.例如： import collections help(collections)可以在collections的__init__.py中找到help函数返回的内容 Python代码中其他地方出现的字符串也可以作为文档，但是其不会被Python字节编码器识别，也就无法作为运行时对象属性（也就无法被分配给__doc__方法），但是有两种额外类型的docstrings可以被软件工具提取。 在模块、类或者__init__方法最开始地方简单的赋值语句之后的字符串，被称为“属性说明文档” (attribute docstrings) 紧跟着另一个docstrings出现的字符串称为“附加文档”（dditional docstrings） 参考PEP 258，查看关于属性文档和附加文档的详细说明 为了保证一致性， 在文档字符串周围使用 """your docstring"""。如果在文档字符串中使用任何反斜杠转义，那么需要用r"""your raw docstring"""。对于 Unicode 文档字符串，请使用 u"""your Unicode docstring """。 1.2 docstring的表现形式python的docstring有两种，一种是单行，一种是多行（就是字面意思，有的注释文档是写在一行，有的需要回车，写成多行） 单行docstring 单行docstring适用于极少数情况，你的说明文档恰好可以写在一行里面，这时候可以使用单行docstring。 def kos_root(): """Return the pathname of the KOS root directory.""" global _kos_root if _kos_root: return _kos_root ...注意： 即使字符串适合一行，也使用三引号，这样以后扩展起来比较容易结束引号与开始引号在同一行，这样单行看起来好看在文档字符串之前或之后都没有空行。文档字符串是以句号结尾的短语，描述的内容应该是"Do this", "Return that"，这个函数是用来干嘛的，函数参数如何，函数返回什么，不应该写其他无关内容。单行文档字符串的内容，不应该是函数/方法的重复说明，比如下面这种就不值得提倡 def function(a, b): """function(a, b) -> list"""最好应该是这样的： def function(a, b): """Do X and return a list."""
多行docstring 多行docstrings由一个总结/总结行（类似单行说明文档）、一个空行，然后是其他更详细的内容描述。摘要行可以被自动索引工具使用，因此它需要符合位于第一行且后面空一行以和其他部分隔开这样的规范。总结行可以和开始的引号在一行，也可以在下一行。整个文档的缩进和第一行一样，如下面的例子。一个类的所有docstrings后面，要插入一个空行。（和后面的代码隔开）一般类方法会用一个空行和其他内容分开，docstrings和第一个方法之间要有个空格脚本（一个独立程序，比如一个.py文件）的docstring应该可以作为它的usage信息，比如脚本被不正确的调用，或者还使用-h参数时，就会打印出这个信息。这样的docstring应该记录了脚本的函数功能，还有命令行语法，环境变量以及文件等等。用法消息可能会很多，甚至好几个屏幕，但是起码要写的能让新用户可以正确使用这个脚本，同时对于熟练用户来说也是一个所有功能列表的快速参考。不要使用 Emacs 约定在运行文本中以大写形式提及函数或方法的参数。 Python 区分大小写，参数名称可用于关键字参数，因此文档字符串应记录正确的参数名称。最好在单独的行中列出每个参数。 示例1： def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ...
示例2： class Variable: """ Attributes: history (:class:`History` or None) : the Function calls that created this variable or None if constant derivative (variable type): the derivative with respect to this variable grad (variable type) : alias for derivative, used for tensors name (string) : a globally unique name of the variable """ def __init__(self, history, name=None): global variable_count assert history is None or isinstance(history, History), history self.history = history self._derivative = None # This is a bit simplistic, but make things easier. variable_count += 1 self.unique_id = "Variable" + str(variable_count) # For debugging can have a name. if name is not None: self.name = name else: self.name = self.unique_id self.used = 0 def requires_grad_(self, val): """ Set the requires_grad flag to `val` on variable. Ensures that operations on this variable will trigger backpropagation. Args: val (bool): whether to require grad """ self.history = History() 2. Google Styleguide来源：https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings 直接看模板就好了 2.1 模块docstrings如果是一个模块，那么文件的最开始，应该有类似以下内容： """A one line summary of the module or program, terminated by a period. Leave one blank line. The rest of this docstring should contain an overall description of the module or program. Optionally, it may also contain a brief description of exported classes and functions and/or usage examples. Typical usage example: foo = ClassFoo() bar = foo.FunctionBar() """2.2 函数和方法 文档字符串应该提供足够的信息来编写对函数的调用，而无需阅读函数的代码。文档字符串应描述函数的调用语法及其语义，但通常不描述其实现细节，除非这些细节与函数的使用方式相关函数的描述信息中有几个部分是比较特殊，需要进行特殊指明的。比如：参数，按名称列出每个参数，名称后面就跟着描述，用冒号/空格/换行符分开名称和描述。如果描述信息太长，单行超过80个字符，可以使用比参数名称多2或4个空格的悬空缩进（与文件中其余的docstring保持一致）。如果代码不包含相应的类型注释，则说明应包括所需的类型。如果函数接受foo（变长参数列表）和/或**bar（任意关键字参数），则它们应列为foo和**bar。类似的还有return和raise，这两种特殊类型的说明如果是函数和方法，那么其docstring应该类似下面： def fetch_smalltable_rows(table_handle: smalltable.Table, keys: Sequence[Union[bytes, str]], require_all_keys: bool = False, ) -> Mapping[bytes, Tuple[str]]: """Fetches rows from a Smalltable. Retrieves rows pertaining to the given keys from the Table instance represented by table_handle. String keys will be UTF-8 encoded. Args: table_handle: An open smalltable.Table instance. keys: A sequence of strings representing the key of each table row to fetch. String keys will be UTF-8 encoded. require_all_keys: If True only rows with values set for all keys will be returned. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {b'Serak': ('Rigel VII', 'Preparer'), b'Zim': ('Irk', 'Invader'), b'Lrrr': ('Omicron Persei 8', 'Emperor')} Returned keys are always bytes. If a key from the keys argument is missing from the dictionary, then that row was not found in the table (and require_all_keys must have been False). Raises: IOError: An error occurred accessing the smalltable. """2.3 类 class SampleClass: """Summary of class here. Longer class information.... Longer class information.... Attributes: likes_spam: A boolean indicating if we like SPAM or not. eggs: An integer count of the eggs we have laid. """ def __init__(self, likes_spam: bool = False): """Inits SampleClass with blah.""" self.likes_spam = likes_spam self.eggs = 0 def public_method(self): """Performs operation blah.""" 3. 其他 参考如下链接：minitorch/slides-master/docs/slides+build2/module0.1.html#/14 |
今日新闻 |
点击排行 |
|
推荐新闻 |
图片新闻 |
|
专题文章 |
| CopyRight 2018-2019 实验室设备网 版权所有 win10的实时保护怎么永久关闭 |